Software Vault: The Gold Collection/Software Vault - The Gold Collection (American Databankers) (1993).ISO/cdr09/cascad13.zip/CASCADE.DOC

Text File | 1993-06-01 | 21KB | 484 lines

CASCADE.DOC                                    February 17, 1991.


0. WARNING

Be warned that so far this program has been subjected to only a
minimal amount of beta-testing and debugging. Make backups. Check
the output to make sure it is what was expected. Report all bugs.


1. FILES

This distribution should include the following files (possibly in
CASCADE.ARC):

     RCASCADE.BAT --- sample batch file to run SUBST and CASCADE,
                         to be stored somewhere on the DOS path
     CASCADE.COM --- executable compiled program file
     CASCADE.DOC --- this help file
     CASCADE.PAS --- Turbo PASCAL source code
     CASCADE.STY --- LaTeX style file
     CASCADE.TEX --- main LaTeX file

In addition, running Cascade can create three types of output
files:

     1. an index file
     2. a print to disk file
     3. a subsidiary TeX file

In each of these cases, the program prompts for a file name.
However, it suggests the name TEMP.TEX in the third case, since
otherwise the user will have to edit CASCADE.TEX and make the
appropriate change to the line

\input{temp}

at the end of the file.

Finally, the program takes its input from three of the PAF data
files, namely INDIV2.DAT, MARR2.DAT and NAME2.DAT. It expects to
find these files in drive E:. The DOS command SUBST can be used to
identify drive E: with the drive and pathname in which these files
normally reside. For example, CASCADE.BAT includes the line

SUBST E: C:\PAF\PAFDATA.

The user can edit this line of the batch file as appropriate.
The CONFIG.SYS file must allow for drive E: with the statement

LASTDRIVE=E

say. Thanks to Barbara Bennett for this tip (ABT PAF Jul-Sep 1988
page 31). It may be necessary to reboot your machine before trying
to run the program on another database.

If drive E: already exists, then some other drive such as F: or G:
can be used, but this will require editing and recompiling
CASCADE.PAS.


2. OVERVIEW

Parts of CASCADE.PAS are extensively commented, and the program is
menu driven, so it should be easy to learn. However, some of the
changes in version 1.1 and later versions could be better
documented.

To run the program, edit RCASCADE.BAT, replacing C:\PAF\PAFDATA
with the pathname of your own PAF database which you want to use;
and replacing C:\CASCADE\ with the pathname where you place
CASCADE.COM. Then just type RCASCADE at the DOS prompt. If you have
more than one PAF database, just edit RCASCADE.BAT and reboot your
machine to print charts from a different database.

Here is a brief overview of the program features (more detailed
information is contained in later sections of this help file):

The descendants charts produced by FR.EXE and PAFUTIL.EXE are
woefully inadequate. Particularly annoying is the abbreviation of
dates (born BEF 1988 becomes 1988 etc.) and names: with long
surnames, all given names sometimes reduce to a single initial.
Dave Hurd wrote a program which was a vast improvement, and which
has now been rewritten to display more information and also do
`cascading descendants charts.' In brief, this option displays all
of an individual's blood relations with spouses, outputting one
descendants chart for each ancestral couple (parents, both sets of
grandparents, four sets of grandparents, and so on, if present in
the database). Grandparents descendants are omitted from the
great-grandparents chart etc to avoid duplication.

The descendants charts produced by this program are much more
informative than the PAFUTIL version. The program does NOT search
for individuals, so the user should ascertain the desired RIN
before running CASCADE.

The additional feature enables CASCADE to print basic information
for all the blood relations of any individual in the PAF data base.
The cascading pedigree charts option in PAFUTIL prints pedigree
charts with all of the individual's ancestors; it also has an
option to print a family group record for each ancestral couple.
The cascading descendants charts option in this program instead
prints a descendants chart for each of these couples. Duplication
is avoided by indicating under the parent on the grandparents'
chart which descendants chart contains (starting on its first page)
the parent's own descendants, rather than reproducing these three
times (on the parents' own chart, and on the chart of each set of
grandparents); and so on for earlier generations.
This cross referencing also works for any family which is doubly
related to the root individual. The second time the family is
encountered, a message is printed referring the reader to the page
and chart where that family and its descendants are printed.

A number of variations on these basic options are also provided;
details are given under the relevant menu options below.


3. ACKNOWLEDGEMENTS

This program is based on another originally developed by

          David A. Hurd
          1405 Cottage Street SW
          Vienna, Virginia 22180
          USA

          Phone: [phone]

and distributed through the disk library of the Capital PAF User's
Group (CPAFUG). My apologies to Mr Hurd if he feels that there has
been any breach of copyright.

The program was substantially extended by

          Patrick J. Waldron
          39 Park Drive
          Dublin 6
          Ireland

          Phone: [phone]

          E-mail: [e-mail]
          or:        [e-mail]
          or:        [e-mail]

A number of minor modifications were suggested by

          Barbara Bennett
          6426 Pound Apple Ct
          Columbia, MD 21045
          USA

          Phone: [phone]

Parts of a PAF wish list (which Patrick Waldron sent to Barbara
Bennett on the CPAFUG bulletin board) made it into print in ABT PAF
Apr-Jun 1989 page 8. In particular, item W under Reports prompted
from Steve Cannon the request: `Would you be willing to provide the
code for this? Or at least examples of how you would like it to
appear?' That was what first prompted circulation, documentation
and improvement of this program.

See also comments in ABT PAF Oct-Dec 1990 page 21 and Jan-Mar 1991
page 17. (` ... still incomplete but promising when the author
completes the software.')

Please report bugs (presumably still numerous) and suggest
improvements to Patrick Waldron.


4. MODIFICATION HISTORY

Version 1.3, February 17, 1991.

Two new menu options added:

     print to disk file
     .TeX output file

Cascading by surname option fixed and can now be limited to m
generations, if desired.

Version 1.2, August 19, 1990.

Menus and user interface tidied up;
configuration file eliminated.

Version 1.1, April 14, 1990.

Improvements recommended in a letter from Barbara Bennett
implemented.

Version 1.0, October 9, 1989.

The first version made available for general distribution.

The program reads the data files of PAF versions 2.0, 2.1 and 2.2.
It can be used with other genealogy software by exporting data to
a GEDCOM file and importing the GEDCOM file into PAF.


5. MENU OPTIONS

The main menu has thirteen options, and should be self-explanatory.
The first ten options are used to change the configuration, the
next two options actually produce the output, and the final option
returns control to DOS. The above overview and intelligent use of
the menu should be sufficient introduction to the program. The
following descriptions should be considered as a reference manual.
The options are as follows:

     1. Toggle paging/scrolling. Default value paging.

     When compiling descendants charts, the program always displays
     them on the screen. This display can be made to page, allowing
     the user to inspect the chart before printing it or saving it
     to a file. Alternatively, it can be made to scroll, allowing
     the user to leave the machine while running a lengthy job. It
     is also possible to switch from paging to scrolling by typing
     `S<Enter>' after any screenful of data is displayed.

     2. Toggle all descendants/male line only. Default value all
     descendants.

     Those who are interested in a particular surname may find this
     option useful. When set to male line only, each descendants
     chart includes only direct male line descendants of the root
     individual.

     3. Toggle printer on/off. Default value off.

     When the printer is turned on, charts are output to the PASCAL
     virtual file `lst,' which is normally the main dot matrix
     printer. The printer codes are for STAR NX-1000 printers, but
     are easily changed in CASCADE.PAS, which can then be
     recompiled (search for chr( to find all the codes). The print
     head should be lined up with the top of a page before
     selecting this option, although a prompt is issued later.
     Switching off the printer to adjust the paper also switches
     off condensed mode, so charts will be garbled.

     4. Toggle cascade by surname / by generation. Default is by
     generation.

     When cascading by generation, the program produces a
     descendants chart for each individual in the first m
     generations of the root individual's ahnentafel table, a total
     of 2^m charts if the table is complete. There is also some
     logic to printing by surname rather than by generation, as
     suggested by Barbara Bennett. When cascading by surname, the
     program will only print a descendants chart for an ancestor
     with no parents, or on the mth and last generation of the
     ahnentafel table. If the table is complete, then cascading by
     surname will produce 2^(m-1) charts. This is equivalent to
     printing one chart for each surname among the root
     individual's ancestors (assuming that there are no repeated
     surnames). To avoid losing intervening generations, this
     option can only be run with a larger value than m for the
     number of generations on each chart. A warning message is
     printed and the value of m is reset if the user changes any of
     m, n and the surname flag in contravention of this
     restriction.

     Cascading by surname reduces by half the total number of
     charts produced. This is particularly useful when there are
     repeated lines of ancestry, leading to many duplicate charts
     being produced (differing only in the Ahnentafel number, and
     containing only the base couple and a reference to where their
     descendants are printed).

     5. Toggle index file creation on/off. Default is off.

     This option allows an index to be written (unsorted) to a file
     whose name is prompted for. That file can later be sorted with
     the DOS sort utility, or in WordPerfect, or otherwise. Be sure
     to reset the margins in WordPerfect to zero, since some of the
     index entries can be quite long. The format of the index line
     is functional, but not pretty.

     Since there are fewer lines per page in the TeX output than in
     the ASCII output, there are two different sets of page
     numbers. When TeX is on, the page numbers in the index refer
     to the TeX output. To get an index to the ASCII output,
     cascade must be run with TeX off. When TeX is on, the cross
     reference page numbers also refer to the TeX output. To get
     correct cross references in the ASCII output, cascade must be
     run with TeX off.

     WARNING: For this and the next two options, the specified file
     is overwritten. Thus, for example, to produce two index files
     from one session of the program, it is essential to choose two
     different file names.

     6. Toggle print file creation on/off. Default is off.

     This option just saves the printer output to disk for later
     printing or inspection on screen. It might also be a paper
     saver if the printer chews or runs out of paper half way
     through a long job and it is desired to restart in the middle
     of the output.

     7. Toggle TeX file creation on/off. Default is off. Default
     filename is TEMP.TEX.

     This option is only useful if you have access to the TeX
     (mathematical typesetting) software. The files CASCADE.TEX and
     CASCADE.STY contain the LaTeX macros etc which are used. A
     \input command in CASCADE.TEX reads TEMP.TEX, and can be
     amended to read from whatever alternative output file is
     specified by the user. Note that these are LaTeX files, not
     plain TeX or any other format.

     8. Change no. of generations per chart. Default is 99.

     The base individual on a chart is numbered 1; his or her
     children are numbered 2 (and indented once); grandchildren are
     numbered 3 (and indented twice); and so on. When this option
     is used to set the number of generations per chart to n,
     descendants whose generation number would be greater than n
     are omitted from the chart. In the unlikely event that a chart
     with more than 99 generations is required, and that a wide
     enough printer and paper are available, the constant maxgen in
     CASCADE.PAS can be changed and the program recompiled.

     9. Change no. of generations to cascade. Default is 6.

     When this parameter is set to m, then all the descendants
     (down to the nth generation, n>m) of every individual in the
     first m generations of ancestors of the root individual are
     displayed. That includes collateral relations as far as
     (m-1)st cousins at various removes.

     A. (or a.) Change root individual. Default RIN is 1.

     This option is used to specify the RIN of the individual whose
     descendants are to be printed in the case of a single chart.
     For cascading charts, a chart is produced for the root
     individual's parents, two sets of grandparents, four sets of
     greatgrandparents, etc. (but not for the root individual,
     unless none of these ancestors are in the database). It is not
     possible to search the PAF database from within this program,
     so a note of the desired RIN should be made while running FR,
     or it can be determined by consulting other printouts.

     B. Produce a single descendants chart.

     The basic and original output of this program is a descendants
     chart similar to the one in FR.EXE/PAFUTIL.EXE, but differing
     in that it can print a virtually unlimited number of
     generations (up to 99) and will do it in compressed form.
     David Hurd's original program output differed from the
     FR.EXE/PAFUTIL.EXE output in the following ways:

     - names not abbreviated if too long
     - no option to force surnames to uppercase
     - full birth date and bplace3 given, not just (approx) birth
     year.

     Patrick Waldron's modifications are as follows:
     - bplace1, bplace2, bplace3 and bplace4 all given
     - same information given for death as for birth
     - christening or burial information substituted if there is no
     birth or death information respectively
     - file GDEFS.PAS included in program file CASCADE.PAS
     - page headings modified to be more prominent
     - lines per page reduced from 78 to 69 (condensed) to
     accomodate headings
     - Multiple marriages are now numbered. It was sometimes
     confusing when there were no children listed for a first
     marriage, and the 'm-' for a subsequent marriage appeared to
     refer to the 's-' person, so the 'm-' has been moved back one
     space towards the left edge of the page.

     An option is provided to allow the same information to be
     displayed on a chart produced with LaTeX from one of the
     program output files. This allow much more presentable output
     to be automatically generated, without importing printouts
     into a DTP system on a once-off basis.
     C. Produce cascading descendants charts.

     Charts are numbered according to the Ahnentafel system. In
     fact, the number of a chart is one half of the Ahnentafel
     number in the root individual's Ahnentafel table of the person
     at the top of the chart. There are cross references giving the
     number of the chart and page to be consulted for descendants
     who are not repeated.

     In general, the number of a chart is the Ahnentafel number of
     the direct ancestor who appears in generation 2 on the chart.
     However, when there are repeated lines of ancestry, some
     charts will have generation 2 replaced with a cross
     referencing message, and some direct ancestors will not appear
     on the chart corresponding to their own Ahnentafel number.

     No family of children is printed more than once (this is also
     the case for single descendants charts when cousins marry and
     their offspring might appear twice on the descendants chart of
     a common ancestor). When an MRIN is processed subsequently,
     instead of printing details of the children, the program
     prints a message with directions to the chart and page on
     which they are to be found. In the TeX output, this
     information appears in a footnote at the bottom of the page.

     In theory, the cascading charts produced when going back m
     generations should be an exact subset of those produced when
     going back m+k generations. However, some anomalies or
     exceptions may arise when there is a cross-reference in the
     first m generations to a doubly related family printed on a
     chart beyond generation m.

     A chart is printed for every known ancestor, as often as that
     ancestor appears in the Ahnentafel table. Duplicated ancestors
     have brief charts printed with each Ahnentafel number, but
     their descendants are printed only the first time.

     The program outputs a total page count and a total families
     count at the end of each cascade. The page count refers to 69-
     line printer pages and not to 46-line TeX pages.

     0. Return to system. Self-explanatory.


6. MISCELLANEOUS TECHNICAL DETAILS

The NAME2.DAT file is fairly straightforward if one is only
retrieving names as is done here. To update this file, on the other
hand, requires traversing the binary tree as described in the PAF
developers' document.

The PASCAL program reads the INDIV2.DAT and MARR2.DAT files as
arrays of BYTEs and then the PROCEDUREs 'unpack' and 'unp_marr'
perform the necessary translation of the coded information into
strings and integers which can be used for printing.

Future versions may improve the index layout by getting the chart
and page numbers flush right. The reason for the ugly format is
that to get integers into a string in PASCAL it is necessary (I
think) to specify the number of characters, as is done with the
RIN, but it would probably slow things down too much to this with
each chart and page number in the index.

Run-time errors are likely if too many ancestors or descendants are
stacked for future processing.

A description of the function of each segment of the program is
included with the code.

It was necessary to make the chart number of TYPE REAL rather than
TYPE INTEGER since MAXINT is so small in PASCAL (16 generations
would exhaust the integers), but this should not cause any
problems.

A list rather than an array should have been used to handle the
cross referencing. This may be rectified in a future version. If
there are more than 2500 families in the database, it may be
necessary to change the constant, maxfam, in CASCADE.PAS and
recompile.

The charts will eventually run over the right edge of the page, but
this problem can be reduced by changing the number of spaces each
generation is indented, given by the constant indent_size, in
CASCADE.PAS and recompiling. This could be done on a once off basis
whenever a particularly large chart is required, since the current
indentation seems quite pleasing. CASCADE.TEX also contains
instructions on how to change the indentation in the TeX output.
(This can be done without regenerating the file TEMP.TEX.)

It was possible to crash a previous version of the program (with
lots of duplication in the output and no cross referencing),
presumably because of stack overflow, with a cascading pedigree and
even with a particularly large single descendants chart. Now that
duplication has been eliminated, this should happen much less
frequently. In college programming courses, one is always taught
that recursion is the most elegant way of doing things, but it may
sometimes require the compiler to be rewritten to avoid overflow!
Future modifications may include rewriting the descend procedure to
eliminate the recursion there.

Unfortunately, the PASCAL source code, having been altered so many
times, is no longer very pretty. If anyone wants to send me a
program to `pretty' PASCAL source files on a PC, it will be
gratefully received.

Paddy Waldron